<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>glob</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_005_848">&nbsp;</a>NAME</h4><blockquote>
glob, globfree - generate pathnames matching a pattern
</blockquote><h4><a name = "tag_000_005_849">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="glob.h.html">glob.h</a>&gt;

int glob(const char *<i>pattern</i>, int <i>flags</i>,
    int(*<i>errfunc</i>)(const char *<i>epath</i>, int <i>errno</i>), glob_t *<i>pglob</i>);
void globfree(glob_t *<i>pglob</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_005_850">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>glob()</i>
function is a pathname generator that implements the rules
defined in the <b>XCU</b> specification, <b>Section 2.13</b>, <b>Pattern Matching Notation</b>,
with optional support for rule 3 in the <b>XCU</b> specification, <b>Section 2.13.3</b>, <b>Patterns Used for Filename Expansion</b>.
<p>
The structure type
<b>glob_t</b>
is defined in the header
<i><a href="glob.h.html">&lt;glob.h&gt;</a></i>
and includes at least the following members:
<p><table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Member Type</b>
<th align=center><b>Member Name</b>
<th align=center><b>Description</b>
<tr valign=top><td align=left>size_t
<td align=left>gl_pathc
<td align=left>Count of paths matched by <i>pattern</i>.
<tr valign=top><td align=left>char **
<td align=left>gl_pathv
<td align=left>Pointer to a list of matched pathnames.
<tr valign=top><td align=left>size_t
<td align=left>gl_offs
<td align=left>Slots to reserve at the beginning of <b>gl_pathv</b>.
</table>
<p>
The argument
<i>pattern</i>
is a pointer to a pathname pattern to be expanded.  The
<i>glob()</i>
function matches all accessible pathnames against this pattern and
develops a list of all pathnames that match.
In order to have access to a pathname,
<i>glob()</i>
requires search permission on every component of a path except the last,
and read permission on each directory
of any filename component of
<i>pattern</i>
that contains any of the following special characters:
<pre>
<code>
*    ?    [
</code>
</pre>
<p>
The
<i>glob()</i>
function stores the number of matched pathnames into
<i>pglob->gl_pathc</i>
and a pointer to a list of pointers to pathnames into
<i>pglob->gl_pathv</i>.
The pathnames are in sort order as defined by
the current setting of the LC_COLLATE category, see
the <b>XBD</b> specification, <a href="../xbd/locale.html#tag_005_003_002"><b>LC_COLLATE</b>&nbsp;</a> .
The first pointer after the last pathname is a null pointer.
If the pattern does not match any pathnames, the returned
number of matched paths is set to 0, and the contents of
<i>pglob->gl_pathv</i>
are implementation-dependent.
<p>
It is the caller's responsibility to create the structure pointed to by
<i>pglob</i>.
The
<i>glob()</i>
function allocates other space as needed, including the memory pointed to by
<i>gl_pathv</i>.
The
<i>globfree()</i>
function frees any space associated with
<i>pglob</i>
from a previous call to
<i>glob()</i>.
<p>
The
<i>flags</i>
argument is used to control the behaviour of
<i>glob()</i>.
The value of
<i>flags</i>
is a bitwise inclusive OR of zero or more of the following
constants, which are defined in the header
<i><a href="glob.h.html">&lt;glob.h&gt;</a></i>:
<dl compact>

<dt>GLOB_APPEND<dd>
Append pathnames generated to the ones from a previous call to
<i>glob()</i>.

<dt>GLOB_DOOFFS<dd>
Make use of
<i>pglob->gl_offs</i>.
If this flag is set,
<i>pglob->gl_offs</i>
is used to specify how many null
pointers to add to the beginning of
<i>pglob->gl_pathv</i>.
In other words,
<i>pglob->gl_pathv</i>
will point to
null pointers, followed by
pathname pointers, followed by a null pointer.
<dt>GLOB_ERR<dd>
Causes
<i>glob()</i>
to return when it encounters a directory that it cannot open or read.
Ordinarily,
<i>glob()</i>
continues to find matches.


<dt>GLOB_MARK<dd>
Each pathname that is a directory that matches
<i>pattern</i>
has a slash appended.


<dt>GLOB_NOCHECK<dd>
Support rule 3 in the <b>XCU</b> specification, <b>Section 2.13.3</b>, <b>Patterns Used for Filename Expansion</b>.
If
<i>pattern</i>
does not match any pathname, then
<i>glob()</i>
returns a list consisting of only
<i>pattern</i>,
and the number of matched pathnames is 1.

<dt>GLOB_NOESCAPE<dd>
Disable backslash escaping.

<dt>GLOB_NOSORT<dd>
Ordinarily,
<i>glob()</i>
sorts the matching pathnames according to the
current setting of the LC_COLLATE category, see
the <b>XBD</b> specification, <a href="../xbd/locale.html#tag_005_003_002"><b>LC_COLLATE</b>&nbsp;</a> .
When this flag is used the order of
pathnames returned is unspecified.

</dl>
<p>
The GLOB_APPEND
flag can be used to append a new set of pathnames to those found in a
previous call to
<i>glob()</i>.
The following rules apply when two or more calls to
<i>glob()</i>
are made with the same value of
<i>pglob</i>
and without intervening calls to
<i>globfree()</i>:
<ol>
<p>
<li>
The first such call must not set GLOB_APPEND.
All subsequent calls must set it.
<p>
<li>
All the calls must set GLOB_DOOFFS, or all must not set it.
<p>
<li>
After the second call,
<i>pglob->gl_pathv</i>
points to a list containing the following:
<ol type = a>
<p>
<li>
Zero or more null pointers, as specified by GLOB_DOOFFS and
<i>pglob->gl_offs</i>
<p>
<li>
Pointers to the pathnames that were in the
<i>pglob->gl_pathv</i>
list before the call, in the same order as before.
<p>
<li>
Pointers to the new pathnames generated by the second call, in the
specified order.
<p>
</ol>
<p>
<li>
The count returned in
<i>pglob->gl_pathc</i>
will be the total number of pathnames from the two calls.
<p>
<li>
The application can change any of the fields after a call to
<i>glob()</i>.
If it does, it must reset them to the original value before a subsequent
call, using the same
<i>pglob</i>
value, to
<i>globfree()</i>
or
<i>glob()</i>
with the GLOB_APPEND flag.
<p>
</ol>
<p>
If, during the search, a directory is encountered that
cannot be opened or read and
<i>errfunc</i>
is not a null pointer,
<i>glob()</i>
calls
(<i>*errfunc</i>())
with two arguments:
<ol>
<p>
<li>
The
<i>epath</i>
argument is a pointer to the path that failed.
<p>
<li>
The
<i>errno</i>
argument is the value of
<i>errno</i>
from the failure, as set by
<i><a href="opendir.html">opendir()</a></i>,
<i><a href="readdir.html">readdir()</a></i>
or
<i><a href="stat.html">stat()</a></i>.
(Other values may be used to report other errors not explicitly
documented for those functions.)
<p>
</ol>
<p>
The following constants are defined as error return values for
<i>glob()</i>:
<dl compact>

<dt>GLOB_ABORTED<dd>
The scan was stopped because GLOB_ERR was set or
(<i>*errfunc</i>())
returned non-zero.

<dt>GLOB_NOMATCH<dd>
The pattern does not match any existing pathname, and GLOB_NOCHECK was not
set in flags.

<dt>GLOB_NOSPACE<dd>
An attempt to allocate memory failed.

</dl>
<p>
If
<i>(*errfunc)</i>()
is called and returns non-zero, or if the GLOB_ERR flag is set in
<i>flags</i>,
<i>glob()</i>
stops the scan and returns GLOB_ABORTED after setting
<i>gl_pathc</i>
and
<i>gl_pathv</i>
in
<i>pglob</i>
to reflect the paths already scanned.
If GLOB_ERR is not set and either
<i>errfunc</i>
is a null pointer or
(<i>*errfunc</i>())
returns 0, the error is ignored.
</blockquote><h4><a name = "tag_000_005_851">&nbsp;</a>RETURN VALUE</h4><blockquote>
On successful completion,
<i>glob()</i>
returns 0.
The argument
<i>pglob->gl_pathc</i>
returns the number of matched pathnames and the argument
<i>pglob->gl_pathv</i>
contains a pointer to a null-terminated list of matched
and sorted pathnames.
However, if
<i>pglob->gl_pathc</i>
is 0, the content of
<i>pglob->gl_pathv</i>
is undefined.
<p>
The
<i>globfree()</i>
function returns no value.
<p>
If
<i>glob()</i>
terminates due to an error, it returns one of the
non-zero constants
defined in
<i><a href="glob.h.html">&lt;glob.h&gt;</a></i>.
The arguments
<i>pglob->gl_pathc</i>
and
<i>pglob->gl_pathv</i>
are still set as defined above.
</blockquote><h4><a name = "tag_000_005_852">&nbsp;</a>ERRORS</h4><blockquote>
No errors are defined.
</blockquote><h4><a name = "tag_000_005_853">&nbsp;</a>EXAMPLES</h4><blockquote>
One use of the GLOB_DOOFFS flag is by applications that
build an argument list for use with
<i><a href="exec.html">execv()</a></i>,
<i><a href="exec.html">execve()</a></i>
or
<i><a href="exec.html">execvp()</a></i>.
Suppose, for example, that an application wants to do the equivalent of:
<pre>
<code>
ls -l *.c
</code>
</pre>
but for some reason:
<pre>
<code>
system("ls -l *.c")
</code>
</pre>
is not acceptable.
The application could obtain approximately the same result using the sequence:
<pre>
<code>
globbuf.gl_offs = 2;
glob ("*.c", GLOB_DOOFFS, NULL, &amp;globbuf);
globbuf.gl_pathv[0] = "ls";
globbuf.gl_pathv[1] = "-l";
execvp ("ls", &amp;globbuf.gl_pathv[0]);
</code>
</pre>
<p>
Using the same example:
<pre>
<code>
ls -l *.c *.h
</code>
</pre>
could be approximately simulated using GLOB_APPEND as follows:
<pre>
<code>
globbuf.gl_offs = 2;
glob ("*.c", GLOB_DOOFFS, NULL, &amp;globbuf);
glob ("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &amp;globbuf);
 ...
</code>
</pre>
</blockquote><h4><a name = "tag_000_005_854">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
This function is not provided for the purpose of enabling utilities to perform
pathname expansion on their arguments, as this operation is performed by the
shell, and utilities are explicitly not expected to redo this.  Instead, it is
provided for applications that need to do pathname expansion on strings
obtained from other sources, such as a pattern typed by a user or read from a
file.
<p>
If a utility needs to see if a pathname matches a given pattern, it can use
<i><a href="fnmatch.html">fnmatch()</a></i>.
<p>
Note that
<b>gl_pathc</b>
and
<b>gl_pathv</b>
have meaning even if
<i>glob()</i>
fails.  This allows
<i>glob()</i>
to report partial results in the event of an error.  However, if
<b>gl_pathc</b>
is 0,
<b>gl_pathv</b>
is unspecified even if
<i>glob()</i>
did not return an error.
<p>
The GLOB_NOCHECK option could be used when an application wants to expand
a pathname if wildcards are specified,
but wants to treat the pattern as just a string otherwise.
The
<i><a href="../xcu/sh.html">sh</a></i>
utility might use this for option-arguments, for example.
<p>
The new pathnames generated by a subsequent call with GLOB_APPEND
are not sorted together with the previous pathnames.
This mirrors
the way that the shell handles pathname expansion when multiple
expansions are done on a command line.
<p>
Applications that need tilde and parameter expansion should use
<i><a href="wordexp.html">wordexp()</a></i>.
</blockquote><h4><a name = "tag_000_005_855">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_856">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="exec.html">execv()</a></i>,
<i><a href="fnmatch.html">fnmatch()</a></i>,
<i><a href="opendir.html">opendir()</a></i>,
<i><a href="readdir.html">readdir()</a></i>,
<i><a href="stat.html">stat()</a></i>,
<i><a href="wordexp.html">wordexp()</a></i>,
<i><a href="glob.h.html">&lt;glob.h&gt;</a></i>,
the <b>XCU</b> specification.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from the ISO POSIX-2 standard.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

